Developing Integrations
Reserved Names
Policy Manager reserves the namespace <os-name>_PolicyManagerInternal for its own internal device integrations. Third-party integrations may not use names ending with '_PolicyManagerInternal'.
Internal Integrations
Internal integrations are read-only, and may not be modified. If an integration document representing an internal integration is modified, it will be regenerated when the application restarts. In order to implement a third-party device integration for a device type already internally supported by Policy Manager, give it a unique name and use device type settings to select it over the internal implementation.
Load-Time Considerations
Integrations are loaded at application start time and when the integration is posted to the integration API. At that time, their templates are loaded into Template Builder, and their mapper code is evaluated using a virtual machine.
The virtual machine isolates your mapper code from the system context it executes in. As such, it will not be able to require modules, access the process global, or use system resources.
Policy Manager provides the functional utility library 'Ramda' as a global under the name 'ramda' within the context your mapper module executes in as a measure for the sake of convenience.
Your code is not allowed to execute for longer than 100 ms while initializing the module. This is not a limit on the allowed execution time of your individual functions, but you cannot use more than 100 ms to initialize and export your module's implementation.
Update API
Policy Manager provides a RESTful API to create, update, and delete integrations through. The create and update operations are both accessed through POST <iap-host>/policy-manager/integrations. If there is already an integration identified by the name you provide, it will be updated with the other parameters in your request body. If there is no integration identified by the name you provide, one will be created.
The API takes the following parameters:
| Parameter | Description |
|---|---|
| name | The identifying name for your integration. This is the identifying feature of integrations, and all integrations must be assigned a unique name for Policy Manager to be able to differentiate them from each other. |
| exportTemplate | The Jinja2 template you wish to use to export configuration. It may not be comprised of Jinja2 text content; it must be a Template Builder record, complete with a name, a device type, a template type, and template content. |
| policyTemplates | An array of TextFSM templates to be used to import policies. As with the export template, each template must be a Template Builder record, and cannot be a string of TextFSM content. |
| targetTemplates | An array of TextFSM templates to be used to import targets. As with the export template, each template must be a Template Builder record, and cannot be a string of TextFSM content. |
| mapper | A string of JavaScript implementing your mapper module. |
The update API will return an object stating the status of each import operation. The returned JSON object will have the following keys:
| Key | Description |
|---|---|
| integration | This describes the result of inserting the integration document in MongoDB. |
| policyTemplates | This describes the result of adding or updating the policy import templates through Template Builder. |
| targetTemplates | This describes the result of adding or updating the target import templates through Template Builder. |
| exportTemplate | This describes the result of adding or updating the export template through Template Builder. |
Example Response
{
"integration": {
"n": 1,
"nModified": 0,
"upserted": [
{
"index": 0,
"_id": "5df2ab3aad4cff99c88922ae"
}
],
"ok": 1
},
"policyTemplates": [
{
"name": "cisco_ios_show_ip_access-list",
"n": 1,
"nModified": 1,
"ok": 1
},
{
"name": "cisco_ios_show_ipv6_access-list",
"n": 1,
"nModified": 1,
"ok": 1
}
],
"targetTemplates": [
{
"name": "cisco_ios_get_ip_targets",
"n": 1,
"nModified": 0,
"ok": 1
},
{
"name": "cisco_ios_get_ipv6_targets",
"n": 1,
"nModified": 0,
"ok": 1
}
],
"exportTemplate": {
"name": "cisco_ios_export_access-list",
"n": 1,
"nModified": 0,
"ok": 1
}
}